 /*******************************************************************************
  * Copyright (c) 2000, 2007 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.core.filebuffers;


 import org.eclipse.core.filesystem.IFileStore;
 import org.eclipse.core.internal.filebuffers.FileBuffersPlugin;

 import org.eclipse.core.runtime.IPath;

 import org.eclipse.jface.text.IDocument;
 import org.eclipse.jface.text.source.IAnnotationModel;


 /**
  * A text file buffer manager manages text file buffers for files whose contents
  * is considered text.
  * <p>
  * Clients are not supposed to implement that interface.
  * </p>
  *
  * @since 3.0
  */
 public interface ITextFileBufferManager extends IFileBufferManager {
     
     /**
      * The default text file buffer manager.
      * @since 3.3
      */
     ITextFileBufferManager DEFAULT= FileBuffersPlugin.getDefault().getFileBufferManager();

     /**
      * Returns the text file buffer managed for the file at the given location
      * or <code>null</code> if either there is no such text file buffer.
      * <p>
      * The provided location is either a full path of a workspace resource or
      * an absolute path in the local file system. The file buffer manager does
      * not resolve the location of workspace resources in the case of linked
      * resources.
      * </p>
      *
      * @param location the location
      * @return the text file buffer managed for that location or <code>null</code>
      * @deprecated As of 3.3, replaced by {@link #getTextFileBuffer(IPath, LocationKind)}
      */
     ITextFileBuffer getTextFileBuffer(IPath location);
     
     /**
      * Returns the text file buffer managed for the file at the given location
      * or <code>null</code> if there is no such text file buffer.
      * <p>
      * The type of the provided location is specified by the given
      * <code>locationKind</code>.
      * </p>
      *
      * @param location the location
      * @param locationKind the kind of the given location
      * @return the text file buffer managed for that location or <code>null</code>
      * @see LocationKind
      * @since 3.3
      */
     ITextFileBuffer getTextFileBuffer(IPath location, LocationKind locationKind);
     
     /**
      * Returns the text file buffer managed for the given file store
      * or <code>null</code> if there is no such text file buffer.
      * <p>
      * <strong>Note:</strong> This API must not be used if the given file
      * store maps to a resource contained in the workspace. A file buffer
      * that has been connected using a path will not be found.
      * </p>
      * <p>
      * We had to use a different name than <code>getTextFileBuffer</code> for this method
      * due to https://bugs.eclipse.org/bugs/show_bug.cgi?id=148844
      * </p>
      *
      * @param fileStore the file store
      * @return the text file buffer managed for that file store or <code>null</code>
      * @since 3.3
      */
     ITextFileBuffer getFileStoreTextFileBuffer(IFileStore fileStore);

     /**
      * Returns the text file buffer managed for the given document
      * or <code>null</code> if there is no such text file buffer.
      * <p>
      * <strong>Note:</strong> This method goes through the list
      * of registered buffers and tests whether its document matches
      * the given one. Therefore this method should not be used in
      * performance critical code.
      * </p>
      *
      * @param document the document for which to find the text file buffer
      * @return the text file buffer managed for that document or <code>null</code>
      * @since 3.3
      */
     ITextFileBuffer getTextFileBuffer(IDocument document);

     /**
      * Returns the default encoding that is used to read the contents of text files
      * if no other encoding is specified.
      *
      * @return the default text file encoding
      */
     String getDefaultEncoding();

     /**
      * Creates a new empty document. The document is set up in the same way as
      * it would be used in a text file buffer for a file at the given location.
      * <p>
      * The provided location is either a full path of a workspace resource or
      * an absolute path in the local file system. The file buffer manager does
      * not resolve the location of workspace resources in the case of linked
      * resources.
      * </p>
      *
      * @param location the location used to set up the newly created document
      * @return a new empty document
      * @deprecated As of 3.3, replaced by {@link #createEmptyDocument(IPath, LocationKind)}
      */
     IDocument createEmptyDocument(IPath location);
     
     /**
      * Creates a new empty document. The document is set up in the same way as
      * it would be used in a text file buffer for a file at the given location.
      * <p>
      * The type of the provided location is specified by the given
      * <code>locationKind</code>.
      * </p>
      *
      * @param location the location used to set up the newly created document
      * @param locationKind the kind of the given location
      * @return a new empty document
      * @since 3.3
      */
     IDocument createEmptyDocument(IPath location, LocationKind locationKind);

     /**
      * Creates a new annotation for the given location.
      * <p>
      * The provided location is either a full path of a workspace resource or an
      * absolute path in the local file system. The file buffer manager does not
      * resolve the location of workspace resources in the case of linked
      * resources.
      * </p>
      *
      * @param location the location used to create the new annotation model
      * @return the newly created annotation model
      * @deprecated As of 3.3, replaced by {@link #createAnnotationModel(IPath, LocationKind)}
      */
     IAnnotationModel createAnnotationModel(IPath location);
     
     /**
      * Creates a new annotation for the given location.
      * <p>
      * The type of the provided location is specified by the given
      * <code>locationKind</code>.
      * </p>
      *
      * @param location the location used to create the new annotation model
      * @param locationKind the kind of the given location
      * @return the newly created annotation model
      * @since 3.3
      */
     IAnnotationModel createAnnotationModel(IPath location, LocationKind locationKind);

     /**
      * Returns whether a file at the given location is or can be considered a
      * text file. If the file exists, the concrete content type of the file is
      * checked. If the concrete content type for the existing file can not be
      * determined, this method returns <code>true</code>. If the file does
      * not exist, it is checked whether a text content type is associated with
      * the given location. If no content type is associated with the location,
      * this method returns <code>true</code>.
      * <p>
      * The provided location is either a full path of a workspace resource or an
      * absolute path in the local file system. The file buffer manager does not
      * resolve the location of workspace resources in the case of linked
      * resources.
      * </p>
      *
      * @param location the location to check
      * @return <code>true</code> if the location is a text file location
      * @since 3.1
      * @deprecated As of 3.2, replaced by {@link #isTextFileLocation(IPath, boolean)}
      */
     boolean isTextFileLocation(IPath location);
     /**
      * Returns whether a file at the given location is or can be considered a
      * text file. If the file exists, the concrete content type of the file is
      * checked. If the concrete content type for the existing file can not be
      * determined, this method returns <code>!strict</code>. If the file does
      * not exist, it is checked whether a text content type is associated with
      * the given location. If no content type is associated with the location,
      * this method returns <code>!strict</code>.
      * <p>
      * The provided location is either a full path of a workspace resource or an
      * absolute path in the local file system. The file buffer manager does not
      * resolve the location of workspace resources in the case of linked
      * resources.
      * </p>
      *
      * @param location the location to check
      * @param strict <code>true</code> if a file with unknown content type
      * is not treated as text file, <code>false</code> otherwise
      * @return <code>true</code> if the location is a text file location
      * @since 3.2
      */
     boolean isTextFileLocation(IPath location, boolean strict);
 }

